<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>fwprintf</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_404">&nbsp;</a>NAME</h4><blockquote>
fwprintf, wprintf, swprintf - print formatted wide-character output
</blockquote><h4><a name = "tag_000_005_405">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="stdio.h.html">stdio.h</a>&gt;
#include &lt;<a href="wchar.h.html">wchar.h</a>&gt;

int fwprintf(FILE *<i>stream</i>, const wchar_t *<i>format</i>, ...);
int wprintf(const wchar_t *<i>format</i>, ...);
int swprintf(wchar_t *s, size_t <i>n</i>, const wchar_t *<i>format</i>, ...);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_406">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>fwprintf()</i>
function places output on the named output
<i>stream</i>.
The
<i><a href="wprintf.html">wprintf()</a></i>
function places output on the standard output stream
<i>stdout</i>.
The
<i><a href="swprintf.html">swprintf()</a></i>
function places output followed by the null wide-character
in consecutive wide-characters starting at
<i> *s</i>;
no more than 
<i>n</i>
wide-characters are written, including a terminating null 
wide-character, which is always added (unless 
<i>n</i>
is zero).
<p>
Each of these functions
converts, formats and prints its arguments
under control of the
<i>format</i>
wide-character string.  The
<i>format</i>
is composed of zero or more directives:
<i>ordinary wide-characters</i>,
which are simply copied to the output stream and
<i>conversion specifications</i>,
each of which results in the fetching of zero or more arguments.  The results
are undefined if there are insufficient arguments for the
<i>format</i>.
If the
<i>format</i>
is exhausted while
arguments remain, the excess
arguments are evaluated but are otherwise ignored.
<p>
Conversions can be applied to the
<i>n</i>th
argument after the
<i>format</i>
in the argument list, rather than to the next unused argument.
In this case, the conversion wide-character % (see below) is replaced
by the sequence
<i>%n$</i>,
where n is a decimal integer in the range [1,&nbsp;{NL_ARGMAX}],
giving the position of the argument in the argument list.
This feature provides for the definition of format wide-character
strings that
select arguments in an order appropriate to specific languages
(see the EXAMPLES section).
<p>
In format wide-character strings
containing the
<i>%n$</i>
form of conversion specifications, numbered
arguments in the argument list can be referenced from the format 
wide-character string
as many times as required.
<p>
In format wide-character strings containing the % form of 
conversion specifications,
each argument in the argument list is used exactly once.
<p>
All forms of the
<i>fwprintf()</i>
functions allow for the insertion of
a language-dependent radix character in the output string, output as
a wide-character value.
The radix character is defined
in the program's locale (category LC_NUMERIC).
In the POSIX locale, or in a locale where
the radix character is not defined,
the radix character defaults to a period (.).
<p>
Each conversion specification is introduced by the % wide-character
or by the wide-character sequence
<i>%n$</i>,
after which the following appear in sequence:
<ul>
<p>
<li>
Zero or more
<i>flags</i>
(in any order), which modify the meaning of the conversion specification.
<p>
<li>
An optional minimum
<i>field width</i>.
If the converted value has fewer wide-characters than the field
width, it will be padded with spaces by default
on the left; it will be padded on the right, if the
left-adjustment flag (-),
described below, is given to the field width.
The field width takes the form of an asterisk (*), described
below, or a decimal integer.
<p>
<li>
An optional
<i>precision</i>
that gives the minimum number of digits to appear for the d, i, o, u, x
and X conversions; the number of digits to appear after
the radix character for the e, E and f
conversions; the maximum number of significant digits for the g and G
conversions; or the maximum number of wide-characters
to be printed from a string in s conversions.
The precision takes the form of a period (.) followed either
by an asterisk (*), described below, or an optional decimal digit string,
where a null digit string is treated as 0.  If a precision appears with any
other conversion wide-character, the behaviour is undefined.
<p>
<li>
An optional l (ell) specifying that a following c conversion wide-character
applies to a
<b>wint_t</b>
argument; an optional l specifying that a following s
conversion wide-character applies to a 
<b>wchar_t</b>
argument; an optional h specifying that a following d, i, o, u, x or X
conversion wide-character applies to a type
<b>short int</b>
or type
<b>unsigned short int</b>
argument (the argument will have been promoted according to the
integral promotions, and its value will be converted to type
<b>short int</b>
or
<b>unsigned short int</b>
before printing); an optional h
specifying that a following n
conversion wide-character applies to a pointer to a type
<b>short int</b>
argument; an optional l (ell) specifying that a following d, i, o, u, x or X
conversion wide-character applies to a type
<b>long int</b>
or
<b>unsigned long int</b>
argument; an optional l (ell) specifying that a following n
conversion wide-character applies to a pointer to a type
<b>long int</b>
argument; or an optional L specifying that a following e, E, f, g or G
conversion wide-character applies to a type
<b>long double</b>
argument.
If an h, l or L appears with any other conversion wide-character, the 
behaviour is undefined.
<br>
<p>
<li>
A
<i>conversion wide-character</i>
that indicates the type of conversion to be applied.
<p>
</ul>
<p>
A field width, or precision, or both, may be indicated by an
asterisk (*).
In this case an argument of type
<b>int</b>
supplies the field width or precision.
Arguments specifying field
width, or precision, or both must appear in that order
before the argument, if any, to be converted.
A negative field width is taken as a - flag followed by a
positive field width.
A negative precision is taken as if the precision were omitted.
&nbsp;In format wide-character strings containing the
<i>%n$</i>
form of a conversion specification, a field width or precision may be
indicated by the sequence
<i>*m$</i>,
where
<i>m</i>
is a decimal integer in the range [1,&nbsp;{NL_ARGMAX}] giving
the position in the argument list (after the format argument) of an integer
argument containing the field width or precision, for example:
<pre>
<code>
wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 
</code>
</pre>
<p>
The
<i>format</i>
can contain either numbered argument specifications
(that is,
<i>%n$</i>
and
<i>*m$</i>),
or unnumbered argument specifications (that is, % and *),
but normally not both.
The only exception to this is that %%
can be mixed with the
<i>%n$</i>
form.
The results of mixing numbered and unnumbered argument
specifications in a
<i>format</i>
wide-character string are undefined.
When numbered argument specifications are used, specifying the
<i>N</i>th
argument requires that all the leading arguments,
from the first to the (<i>N-1</i>)th, are
specified in the format wide-character string.
<p>
The flag wide-characters and their meanings are:
<dl compact>

<dt>'<dd>The integer portion of the result of a decimal conversion
(%i, %d, %u, %f, %g or %G)
will be formatted with thousands' grouping wide-characters.
For other conversions the behaviour is undefined.
The non-monetary grouping wide-character is used.

<dt>-<dd>The result of the conversion will be left-justified within the field.
The conversion will be right-justified if this flag is not
specified.

<dt>+<dd>The result of a signed
conversion will always begin with a sign (+ or -).
The conversion will begin with a sign only when a negative value
is converted if this flag is not specified.


<dt>space<dd>If the first wide-character of a signed conversion is not a sign or if
a signed conversion results in no wide-characters, a space
will be prefixed to the result.
This means that if the space and +
flags both appear, the space flag will be ignored.

<dt>#<dd>This flag specifies that the value is to be converted
to an alternative form.
For o conversion, it increases the precision (if necessary) to force
the first digit of the result to be 0.
For x or X conversions, a non-zero result will have 0x (or 0X)
prefixed to it.
For e, E, f, g or G
conversions, the result will always contain a radix character,
even if no digits follow it.
Without this flag, a radix character appears
in the result of these conversions only if a digit
follows it.
For g and G conversions, trailing zeros will
<i>not</i>
be removed from the result
as they normally are.
For other conversions, the behaviour is undefined.

<dt>0<dd>For d, i, o, u, x, X, e, E, f, g and G
conversions, leading zeros (following any indication of sign or
base) are used to pad to the field width; no space padding is
performed.
If the 0 and - flags both appear, the 0 flag will be ignored.
For d, i, o, u, x and X
conversions, if a precision is specified, the 0
flag will be ignored.
If the 0 and ' flags both appear, the grouping
wide-characters are inserted before zero padding.
For other conversions, the behaviour is undefined.

</dl>
<p>
The conversion wide-characters and their meanings are:
<dl compact>

<dt>d,&nbsp;i<dd>The <b>int</b> argument is converted to a signed decimal
in the style <b>[</b>-<b>]</b><i>dddd</i>.
The precision specifies the minimum number of digits to appear;
if the value being converted can be represented in fewer digits,
it will be expanded with leading zeros. The default precision is
1. The result of converting 0 with an explicit precision
of 0 is no wide-characters.

<dt>o<dd>The <b>unsigned int</b> argument is converted to unsigned octal format
in the style <i>dddd</i>.
The precision specifies the minimum number of digits to appear; if
the value being converted can be represented in fewer digits, it will be
expanded with leading zeros. The default precision is 1. The result of
converting 0 with an explicit precision of 0 is no wide-characters.

<dt>u<dd>The <b>unsigned int</b> argument is converted to unsigned decimal format
in the style
<i>dddd</i>.
The precision specifies the minimum number of digits to appear; if
the value being converted can be represented in fewer digits, it will be
expanded with leading zeros. The default precision is 1. The result of
converting 0 with an explicit precision of 0 is no wide-characters.


<dt>x<dd>The <b>unsigned int</b> argument is converted to unsigned hexadecimal format
in the style
<i>dddd</i>;
the letters abcdef are used.
The precision specifies the minimum number of digits to appear; if
the value being converted can be represented in fewer digits, it will be
expanded with leading zeros. The default precision is 1. The result of
converting 0 with an explicit precision of 0 is no wide-characters.


<dt>X<dd>Behaves the same as the x conversion wide-character except that
letters ABCDEF are used instead of abcdef.

<dt>f<dd>The
<b>double</b>
argument is converted to decimal notation in the style
<b>[</b>-<b>]</b><i>ddd.ddd</i>, where the number of digits after the
radix character is equal to the precision specification.
If the precision is missing, it is taken as 6; if the precision is
explicitly 0 and no # flag is present, no radix character appears.
If a radix character appears, at least one digit appears
before it.
The value is rounded to the appropriate number of digits.

The
<i>fwprintf()</i>
family of functions may make available wide-character string 
representations for infinity and NaN.

<dt>e, E<dd>The
<b>double</b>
argument is converted in the style
<b>[</b>-<b>]</b><i>d.ddd</i>e<i>&plusmn;dd</i>,
where there is one digit before the radix character
(which is non-zero if the argument is non-zero) and the number of
digits after it is equal to the precision; if the precision is
missing, it is taken as 6; if the precision is 0 and no # flag
is present, no radix character appears.
The value is rounded to the appropriate number of digits.
The E conversion wide-character will produce a number with E 
instead of e introducing the exponent.
The exponent always contains at least two digits.
If the value is 0, the exponent is 0.

The
<i>fwprintf()</i>
family of functions may make available wide-character string 
representations for infinity and NaN.


<dt>g, G<dd>The
<b>double</b>
argument is converted in the style f or e (or in the style E
in the case of a G conversion wide-character),
with the precision specifying the number of significant digits.
If an explicit precision is 0, it is taken as 1.
The style used depends on the value converted; style e (or E)
will be used only if the exponent resulting from such a
conversion is less than -4 or greater than or equal to the
precision.
Trailing zeros are removed from the fractional portion of the
result; a radix character appears only if it is followed
by a digit.

The
<i>fwprintf()</i>
family of functions may make available wide-character string 
representations for infinity and NaN.


<dt>c<dd>If no l (ell) qualifier is present, the
<b>int</b>
argument is converted to a wide-character as if by calling the
<i><a href="btowc.html">btowc()</a></i>
function and the resulting wide-character is written.  Otherwise the
<b>wint_t</b>
argument is converted to
<b>wchar_t</b>,
and written.


<dt>s<dd>If no l (ell) qualifier is present, the argument must be a pointer to a
character array containing a character sequence beginning in the
initial shift state.
Characters from the array are converted as if by repeated calls
to the
<i><a href="mbrtowc.html">mbrtowc()</a></i>
function, with the conversion state described by an
<b>mbstate_t</b>
object initialised to zero before the first character is
converted, and written up to (but not including) the terminating 
null wide-character.  
If the precision is specified, no
more than that many wide-characters are written.
If the precision is not specified or is greater than the size of
the array, the array must contain a null wide-character.

If an l (ell) qualifier is present, the argument must be a pointer to 
an array of type
<b>wchar_t</b>.
Wide characters from the array are written up to (but not including) a
terminating null wide-character.
If no precision is specified or is greater than the size of the array,
the array must contain a null wide-character.   If a precision is
specified, no more than that many wide-characters are written.

<dt>p<dd>The argument must be a pointer to
<b>void</b>.
The value of the pointer is converted to a sequence of printable
wide-characters, in an implementation-dependent manner.

<dt>n<dd>The argument must be a pointer to an integer into which is written
the number of wide-characters written to the output so far by this 
call to one of the
<i>fwprintf()</i>
functions.
No argument is converted.


<dt>C<dd>Same as <b>lc</b>.

<dt>S<dd>Same as <b>ls</b>.

<dt>%<dd>Output a % wide-character; no argument is converted.
The entire conversion specification must be %%.

</dl>
<p>
If a conversion specification does not match one of the
above forms, the behaviour is undefined.
<p>
In no case does a non-existent or small field width
cause truncation of a field;
if the result of a conversion is wider than the field width,
the field is simply expanded to contain the conversion result.
Characters generated by
<i>fwprintf()</i>
and
<i><a href="wprintf.html">wprintf()</a></i>
are printed as if
<i><a href="fputwc.html">fputwc()</a></i>
had been called.
<p>
The
<i>st_ctime</i>
and
<i>st_mtime</i>
fields of the file will be marked for update between the call to
a successful execution of
<i>fwprintf()</i>
or
<i><a href="wprintf.html">wprintf()</a></i>
and the next successful completion of a call to
<i><a href="fflush.html">fflush()</a></i>
or
<i><a href="fclose.html">fclose()</a></i>
on the same stream or a call to
<i><a href="exit.html">exit()</a></i>
or
<i><a href="abort.html">abort()</a></i>.
</blockquote><h4><a name = "tag_000_005_407">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion, these functions
return the number of wide-characters transmitted
excluding the terminating null wide-character in the case of
<i><a href="swprintf.html">swprintf()</a></i>
or
a negative value if an output error was encountered.
If n or more wide characters were requested to be written
<i><a href="swprintf.html">swprintf()</a></i>
returns a negative value.
</blockquote><h4><a name = "tag_000_005_408">&nbsp;</a>ERRORS</h4><blockquote>
For the conditions under which
<i>fwprintf()</i>
and
<i><a href="wprintf.html">wprintf()</a></i>
will fail and may fail, refer to
<i><a href="fputwc.html">fputwc()</a></i>.
<p>
In addition, all forms of
<i>fwprintf()</i>
may fail if:
<dl compact>

<dt>[EILSEQ]<dd>
A wide-character code that does not correspond to a valid character has been
detected.

<dt>[EINVAL]<dd>
There are insufficient arguments.

</dl>
<p>
In addition,
<i><a href="wprintf.html">wprintf()</a></i>
and
<i>fwprintf()</i>
may fail if:
<dl compact>

<dt>[ENOMEM]<dd>
Insufficient storage space is available.

</dl>
</blockquote><h4><a name = "tag_000_005_409">&nbsp;</a>EXAMPLES</h4><blockquote>
To print the language-independent date and time format, the
following statement could be used:
<pre>
<code>
wprintf (format, weekday, month, day, hour, min);
</code>
</pre>
For American usage,
<i>format</i>
could be a pointer to the wide-character string:
<pre>
<code>
L"%s, %s %d, %d:%.2d\n"
</code>
</pre>
producing the message:
<pre>
<code>
Sunday, July 3, 10:02
</code>
</pre>
whereas for German usage,
<i>format</i>
could be a pointer to the wide-character string:
<pre>
<code>
L"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
</code>
</pre>
producing the message:
<pre>
<code>
Sonntag, 3. Juli, 10:02
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_410">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_411">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_412">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="btowc.html">btowc()</a></i>,
<i><a href="fputwc.html">fputwc()</a></i>,
<i><a href="fwscanf.html">fwscanf()</a></i>,
<i><a href="setlocale.html">setlocale()</a></i>,
<i><a href="mbrtowc.html">mbrtowc()</a></i>,
<i><a href="stdio.h.html">&lt;stdio.h&gt;</a></i>,
<i><a href="wchar.h.html">&lt;wchar.h&gt;</a></i>,
the <b>XBD</b> specification, <a href="../xbd/locale.html"><b>Locale</b>&nbsp;</a>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
